<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- This file documents the use of the GNU compilers.

Copyright (C) 1988-2023 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
"GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<!-- Created by GNU Texinfo 6.7, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Basic Asm (Using the GNU Compiler Collection (GCC))</title>

<meta name="description" content="Basic Asm (Using the GNU Compiler Collection (GCC))">
<meta name="keywords" content="Basic Asm (Using the GNU Compiler Collection (GCC))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html" rel="start" title="Top">
<link href="Indices.html" rel="index" title="Indices">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Using-Assembly-Language-with-C.html" rel="up" title="Using Assembly Language with C">
<link href="Extended-Asm.html" rel="next" title="Extended Asm">
<link href="Using-Assembly-Language-with-C.html" rel="prev" title="Using Assembly Language with C">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en_US">
<span id="Basic-Asm"></span><div class="header">
<p>
Next: <a href="Extended-Asm.html" accesskey="n" rel="next">Extended Asm</a>, Up: <a href="Using-Assembly-Language-with-C.html" accesskey="u" rel="up">Using Assembly Language with C</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<span id="Basic-Asm-_002d_002d_002d-Assembler-Instructions-Without-Operands"></span><h4 class="subsection">6.47.1 Basic Asm &mdash; Assembler Instructions Without Operands</h4>
<span id="index-basic-asm"></span>
<span id="index-assembly-language-in-C_002c-basic"></span>

<p>A basic <code>asm</code> statement has the following syntax:
</p>
<div class="example">
<pre class="example">asm <var>asm-qualifiers</var> ( <var>AssemblerInstructions</var> )
</pre></div>

<p>For the C language, the <code>asm</code> keyword is a GNU extension.
When writing C code that can be compiled with <samp>-ansi</samp> and the
<samp>-std</samp> options that select C dialects without GNU extensions, use
<code>__asm__</code> instead of <code>asm</code> (see <a href="Alternate-Keywords.html">Alternate Keywords</a>).  For
the C++ language, <code>asm</code> is a standard keyword, but <code>__asm__</code>
can be used for code compiled with <samp>-fno-asm</samp>.
</p>
<span id="Qualifiers-1"></span><h4 class="subsubheading">Qualifiers</h4>
<dl compact="compact">
<dt><code>volatile</code></dt>
<dd><p>The optional <code>volatile</code> qualifier has no effect. 
All basic <code>asm</code> blocks are implicitly volatile.
</p>
</dd>
<dt><code>inline</code></dt>
<dd><p>If you use the <code>inline</code> qualifier, then for inlining purposes the size
of the <code>asm</code> statement is taken as the smallest size possible (see <a href="Size-of-an-asm.html">Size of an asm</a>).
</p></dd>
</dl>

<span id="Parameters"></span><h4 class="subsubheading">Parameters</h4>
<dl compact="compact">
<dt><var>AssemblerInstructions</var></dt>
<dd><p>This is a literal string that specifies the assembler code. The string can 
contain any instructions recognized by the assembler, including directives. 
GCC does not parse the assembler instructions themselves and 
does not know what they mean or even whether they are valid assembler input. 
</p>
<p>You may place multiple assembler instructions together in a single <code>asm</code> 
string, separated by the characters normally used in assembly code for the 
system. A combination that works in most places is a newline to break the 
line, plus a tab character (written as &lsquo;<samp>\n\t</samp>&rsquo;).
Some assemblers allow semicolons as a line separator. However, 
note that some assembler dialects use semicolons to start a comment. 
</p></dd>
</dl>

<span id="Remarks"></span><h4 class="subsubheading">Remarks</h4>
<p>Using extended <code>asm</code> (see <a href="Extended-Asm.html">Extended Asm</a>) typically produces
smaller, safer, and more efficient code, and in most cases it is a
better solution than basic <code>asm</code>.  However, there are two
situations where only basic <code>asm</code> can be used:
</p>
<ul>
<li> Extended <code>asm</code> statements have to be inside a C
function, so to write inline assembly language at file scope (&ldquo;top-level&rdquo;),
outside of C functions, you must use basic <code>asm</code>.
You can use this technique to emit assembler directives,
define assembly language macros that can be invoked elsewhere in the file,
or write entire functions in assembly language.
Basic <code>asm</code> statements outside of functions may not use any
qualifiers.

</li><li> Functions declared
with the <code>naked</code> attribute also require basic <code>asm</code>
(see <a href="Function-Attributes.html">Function Attributes</a>).
</li></ul>

<p>Safely accessing C data and calling functions from basic <code>asm</code> is more 
complex than it may appear. To access C data, it is better to use extended 
<code>asm</code>.
</p>
<p>Do not expect a sequence of <code>asm</code> statements to remain perfectly 
consecutive after compilation. If certain instructions need to remain 
consecutive in the output, put them in a single multi-instruction <code>asm</code>
statement. Note that GCC&rsquo;s optimizers can move <code>asm</code> statements 
relative to other code, including across jumps.
</p>
<p><code>asm</code> statements may not perform jumps into other <code>asm</code> statements. 
GCC does not know about these jumps, and therefore cannot take 
account of them when deciding how to optimize. Jumps from <code>asm</code> to C 
labels are only supported in extended <code>asm</code>.
</p>
<p>Under certain circumstances, GCC may duplicate (or remove duplicates of) your 
assembly code when optimizing. This can lead to unexpected duplicate 
symbol errors during compilation if your assembly code defines symbols or 
labels.
</p>
<p><strong>Warning:</strong> The C standards do not specify semantics for <code>asm</code>,
making it a potential source of incompatibilities between compilers.  These
incompatibilities may not produce compiler warnings/errors.
</p>
<p>GCC does not parse basic <code>asm</code>&rsquo;s <var>AssemblerInstructions</var>, which
means there is no way to communicate to the compiler what is happening
inside them.  GCC has no visibility of symbols in the <code>asm</code> and may
discard them as unreferenced.  It also does not know about side effects of
the assembler code, such as modifications to memory or registers.  Unlike
some compilers, GCC assumes that no changes to general purpose registers
occur.  This assumption may change in a future release.
</p>
<p>To avoid complications from future changes to the semantics and the
compatibility issues between compilers, consider replacing basic <code>asm</code>
with extended <code>asm</code>.  See
<a href="https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended">How to convert
from basic asm to extended asm</a> for information about how to perform this
conversion.
</p>
<p>The compiler copies the assembler instructions in a basic <code>asm</code> 
verbatim to the assembly language output file, without 
processing dialects or any of the &lsquo;<samp>%</samp>&rsquo; operators that are available with
extended <code>asm</code>. This results in minor differences between basic 
<code>asm</code> strings and extended <code>asm</code> templates. For example, to refer to 
registers you might use &lsquo;<samp>%eax</samp>&rsquo; in basic <code>asm</code> and
&lsquo;<samp>%%eax</samp>&rsquo; in extended <code>asm</code>.
</p>
<p>On targets such as x86 that support multiple assembler dialects,
all basic <code>asm</code> blocks use the assembler dialect specified by the 
<samp>-masm</samp> command-line option (see <a href="x86-Options.html">x86 Options</a>).  
Basic <code>asm</code> provides no
mechanism to provide different assembler strings for different dialects.
</p>
<p>For basic <code>asm</code> with non-empty assembler string GCC assumes
the assembler block does not change any general purpose registers,
but it may read or write any globally accessible variable.
</p>
<p>Here is an example of basic <code>asm</code> for i386:
</p>
<div class="example">
<pre class="example">/* Note that this code will not compile with -masm=intel */
#define DebugBreak() asm(&quot;int $3&quot;)
</pre></div>

<hr>
<div class="header">
<p>
Next: <a href="Extended-Asm.html" accesskey="n" rel="next">Extended Asm</a>, Up: <a href="Using-Assembly-Language-with-C.html" accesskey="u" rel="up">Using Assembly Language with C</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Indices.html" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
